.\" Copyright (c) 2002-2020 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 20, 2002
.Dt AG_BUTTON 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Button
.Nd agar button widget
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(http://libagar.org/widgets/AG_Button.png, "A row of buttons")
.Nm
is a push-button displaying a text label or an image.
It can trigger events and/or control a boolean value.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INTERFACE
.nr nS 1
.Ft "AG_Button *"
.Fn AG_ButtonNew "AG_Widget *parent" "Uint flags" "const char *format" "..."
.Pp
.Ft "AG_Button *"
.Fn AG_ButtonNewS "AG_Widget *parent" "Uint flags" "const char *label"
.Pp
.Ft "AG_Button *"
.Fn AG_ButtonNewFn "AG_Widget *parent" "Uint flags" "const char *label" "void (*fn)(AG_Event *)" "const char *fnArgs" "..."
.Pp
.Ft "AG_Button *"
.Fn AG_ButtonNewInt "AG_Widget *parent" "Uint flags" "const char *label" "int *p"
.Pp
.Ft "AG_Button *"
.Fn AG_ButtonNewUint "AG_Widget *parent" "Uint flags" "const char *label" "Uint *p"
.Pp
.Ft "AG_Button *"
.Fn AG_ButtonNewFlag "AG_Widget *parent" "Uint flags" "const char *label" "Uint *p" "Uint bitmask"
.Pp
.Ft void
.Fn AG_ButtonSetInverted "AG_Button *button" "int enable"
.Pp
.Ft void
.Fn AG_ButtonSetFocusable "AG_Button *button" "int enable"
.Pp
.Ft void
.Fn AG_ButtonSetSticky "AG_Button *button" "int enable"
.Pp
.Ft void
.Fn AG_ButtonJustify "AG_Button *button" "enum ag_text_justify justify"
.Pp
.Ft void
.Fn AG_ButtonValign "AG_Button *button" "enum ag_text_valign valign"
.Pp
.Ft void
.Fn AG_ButtonSetRepeatMode "AG_Button *button" "int enable"
.Pp
.Ft void
.Fn AG_ButtonSurface "AG_Button *button" "const AG_Surface *su"
.Pp
.Ft void
.Fn AG_ButtonSurfaceNODUP "AG_Button *button" "AG_Surface *su"
.Pp
.Ft void
.Fn AG_ButtonText "AG_Button *button" "const char *format" "..."
.Pp
.Ft void
.Fn AG_ButtonTextS "AG_Button *button" "const char *label"
.Pp
.Ft int
.Fn AG_ButtonGetState "AG_Button *button"
.Pp
.Ft int
.Fn AG_ButtonSetState "AG_Button *button" "int stateNew"
.Pp
.Ft int
.Fn AG_ButtonToggle "AG_Button *button"
.Pp
.nr nS 0
The
.Fn AG_ButtonNew
function allocates, initializes, and attaches an
.Nm .
If
.Fa label
is non-NULL, it sets the initial text label.
For a list of acceptable option
.Fa flags
refer to
.Sx BUTTON FLAGS
below.
.Pp
The
.Fn AG_ButtonNewFn
variant creates a button and also specifies a callback routine to run
whenever it is pressed.
Contrary to 
.Fn AG_ButtonNew ,
it implies
.Dv AG_BUTTON_EXCL
(unless
.Dv AG_BUTTON_NOEXCL
is passed).
.Pp
The
.Fn AG_ButtonNewInt
shorthand creates a button and also sets its
.Sq state
binding to the natural integer at memory location
.Fa p .
.Pp
The
.Fn AG_ButtonNewFlag
shorthand creates a button and also sets its
.Sq state
binding to the value of the bit(s) indicated by
.Fa bitmask
contained within the natural integer at memory location
.Fa p .
.Pp
.Fn AG_ButtonSetInverted
inverts the interpretation of the "state" binding
(sets the
.Dv AG_BUTTON_INVERTED
flag).
.Pp
.Fn AG_ButtonSetFocusable
sets whether the button is allowed to receive focus (0 = No, 1 = Yes).
Default is Yes (see
.Xr AG_WidgetFocus 3 ) .
.Pp
.Fn AG_ButtonSetSticky
sets the behavior of the button when pressed (0 = Momentary, 1 = Sticky).
In Momentary mode, the button springs back to its former state when released.
Default is Sticky.
.Pp
.Fn AG_ButtonJustify
sets the justification mode for the text label.
The
.Fa justify
argument can be
.Dv AG_TEXT_LEFT ,
.Dv AG_TEXT_CENTER
or
.Dv AG_TEXT_RIGHT .
.Pp
.Fn AG_ButtonValign
sets the vertical alignment for the text label.
The
.Fa valign
argument can be
.Dv AG_TEXT_TOP ,
.Dv AG_TEXT_MIDDLE
or
.Dv AG_TEXT_BOTTOM .
.Pp
.Fn AG_ButtonSetRepeatMode
enables or disables Repeat mode.
Repeat mode causes multiple
.Sq button-pushed
events to be posted periodically for as long as the button is triggered
(with an interval of
.Va agMouseSpinIval
ms).
.Pp
.Fn AG_ButtonSurface
sets the button label to a copy of the given surface.
.Fn AG_ButtonSurfaceNODUP
uses the given surface as source without copying (potentially unsafely).
If a label is currently set, it is replaced.
.Pp
.Fn AG_ButtonText
sets the label of the button from the specified text string.
If a surface is currently set, it is removed.
.Pp
.Fn AG_ButtonGetState
returns the current boolean state of the button (1 = pressed, 0 = released).
.Fn AG_ButtonSetState
sets the state to
.Fa stateNew
and returns the previous state.
.Fn AG_ButtonToggle
atomically toggles the state of the button and returns the new state.
.Sh BUTTON FLAGS
The following
.Va flags
are provided:
.Bl -tag -width "AG_BUTTON_MOUSEOVER "
.It AG_BUTTON_STICKY
Prevent the button from springing back to its previous state following
a click.
Set on initialization or by
.Fn AG_ButtonSetSticky .
.It AG_BUTTON_MOUSEOVER
The cursor is over the button area (read-only).
.It AG_BUTTON_REPEAT
Repeat mode is enabled (read-only, see
.Fn AG_ButtonSetRepeatMode ) .
.It AG_BUTTON_PRESSING
The button is being activated (read-only).
.It AG_BUTTON_SET
Set "state" to 1 when the button becomes visible.
.It AG_BUTTON_INVERTED
Invert the interpretation of the "state" binding
(Default: 0=Released, 1=Pressed).
.It AG_BUTTON_EXCL
Disable the test for redrawing the button upon external changes to the
"state" binding.
.It AG_BUTTON_NO_FOCUS
Cannot gain focus (see
.Xr AG_WidgetSetFocusable 3 ) .
.It AG_BUTTON_HFILL
Expand horizontally in parent container.
.It AG_BUTTON_VFILL
Expand vertically in parent container.
.It AG_BUTTON_EXPAND
Shorthand for
.Dv AG_BUTTON_HFILL | AG_BUTTON_VFILL .
.El
.Sh EVENTS
The
.Nm
widget generates the following events:
.Pp
.Bl -tag -compact -width 2n
.It Fn button-pushed "int new_state"
The button was pressed.
If using
.Dv AG_BUTTON_STICKY ,
the
.Fa new_state
argument indicates the new state of the button.
.El
.Sh BINDINGS
The
.Nm
widget provides the following bindings.
In all cases, a value of 1 is considered boolean TRUE, and a value of 0
is considered boolean FALSE.
.Pp
.Bl -tag -compact -width "FLAGS32 *state "
.It Va BOOL *state
Value (1/0) of natural integer
.It Va INT *state
Value (1/0) of natural integer
.It Va UINT *state
Value (1/0) of natural integer
.It Va UINT8 *state
Value (1/0) of 8-bit integer
.It Va UINT16 *state
Value (1/0) of 16-bit integer
.It Va UINT32 *state
Value (1/0) of 32-bit integer
.It Va FLAGS *state
Bits in an int
.It Va FLAGS8 *state
Bits in 8-bit word
.It Va FLAGS16 *state
Bits in 16-bit word
.It Va FLAGS32 *state
Bits in 32-bit word
.El
.Sh EXAMPLES
The following code fragment creates a button and sets a handler function
for the
.Sq button-pushed
event:
.Bd -literal -offset indent
void
MyHandlerFn(AG_Event *event)
{
	AG_TextMsg(AG_MSG_INFO, "Hello, %s!", AG_STRING(1));
}

.Li ...

AG_ButtonNewFn(parent, 0, "Hello", MyHandlerFn, "%s", "world");
.Ed
.Pp
The following code fragment uses buttons to control specific bits in
a 32-bit word:
.Bd -literal -offset indent
Uint32 MyFlags = 0;

AG_ButtonNewFlag32(parent, 0, "Bit 1", &MyFlags, 0x01);
AG_ButtonNewFlag32(parent, 0, "Bit 2", &MyFlags, 0x02);
.Ed
.Pp
The following code fragment uses a button to control an int protected
by a mutex device:
.Bd -literal -offset indent
int MyInt = 0;
AG_Mutex MyMutex;
AG_Button *btn;

AG_MutexInit(&MyMutex);
btn = AG_ButtonNew(parent, 0, "Mutex-protected flag");
AG_BindIntMp(btn, "state", &MyInt, &MyMutex);
.Ed
.Sh SEE ALSO
.Xr AG_Event 3 ,
.Xr AG_Intro 3 ,
.Xr AG_Surface 3 ,
.Xr AG_Toolbar 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
widget first appeared in Agar 1.0.
As of Agar 1.6.0 the
.Fn AG_ButtonSetPadding
call is now deprecated (replaced by
.Xr AG_SetStyle 3
with "padding" attribute).
Agar 1.6.0 also introduced
.Dv AG_BUTTON_SET .
